Skip to content

Fix incompatibilities between docusaurus 2 to 3#3232

Merged
zerbitx merged 1 commit intomainfrom
fix-docs
Apr 24, 2026
Merged

Fix incompatibilities between docusaurus 2 to 3#3232
zerbitx merged 1 commit intomainfrom
fix-docs

Conversation

@zerbitx
Copy link
Copy Markdown
Collaborator

@zerbitx zerbitx commented Apr 24, 2026

Fix generators, for example only 6 #'s are allowed now.

What issue type does this pull request address? (keep at least one, remove the others)
/kind bugfix
/kind documentation

What does this pull request do? Which issues does it resolve? (use resolves #<issue_number> if possible)
resolves #

Please provide a short message that should be published in the DevSpace release notes
Fixed an issue where DevSpace ...

What else do we need to know?

@netlify
Copy link
Copy Markdown

netlify Bot commented Apr 24, 2026

Deploy Preview for devspace-docs ready!

Name Link
🔨 Latest commit 3d1c959
🔍 Latest deploy log https://app.netlify.com/projects/devspace-docs/deploys/69eafe1102ee4e0008673ee2
😎 Deploy Preview https://deploy-preview-3232--devspace-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@zerbitx
Copy link
Copy Markdown
Collaborator Author

zerbitx commented Apr 24, 2026

From claude:

Adversarial Review — fix-docs branch

FAIL — Stale yarn.lock (medium)

mdx-mermaid@^v1.3.0 and mermaid@^11.12.3 are still present as orphaned top-level entries in docs/yarn.lock
(lines 8035 and 8085), even though both were removed from package.json. The lockfile was modified during
this PR (mermaid was bumped from 10.9.3 → 11.12.3 in an earlier step), but the final removal from
package.json wasn't followed by a yarn install to clean up. Running cd docs && yarn install will drop
those entries.


PASS — headingPrefix refactor

Logic is correct: depth + 1 preserves prior behavior, cap at 6 is the stated fix. All three boundary cases
in the test are correct (depth=1 → ## , depth=5 → ######, depth=8 → ######). GenerateReference starts at
depth=1 so depth=0 is unreachable in production — the test coverage is adequate.


PASS — Versioned sidebar ID stripping
Adversarial Review — fix-docs branch

FAIL — Stale yarn.lock (medium)

mdx-mermaid@^v1.3.0 and mermaid@^11.12.3 are still present as orphaned top-level entries in
docs/yarn.lock (lines 8035 and 8085), even though both were removed from package.json. The lockfile was
modified during this PR (mermaid was bumped from 10.9.3 → 11.12.3 in an earlier step), but the final
removal from package.json wasn't followed by a yarn install to clean up. Running cd docs && yarn install
will drop those entries.


PASS — headingPrefix refactor

Logic is correct: depth + 1 preserves prior behavior, cap at 6 is the stated fix. All three boundary
cases in the test are correct (depth=1 → ## , depth=5 → ######, depth=8 → ######). GenerateReference
starts at depth=1 so depth=0 is unreachable in production — the test coverage is adequate.


PASS — Versioned sidebar ID stripping

Removing version-4.x/ and version-5.x/ prefixes from doc IDs, and renaming "version-4.x/adminSidebar" →
"adminSidebar", is the correct Docusaurus 3 migration. Both files sharing the key "adminSidebar" is fine
— they're namespaced per-version internally.


PASS — Mermaid removal

No MDX file under docs/pages/ or docs/versioned_docs/ uses a component or mermaid fenced
block. The removal is clean. (The lockfile staleness above is the only artifact.)


PASS — Schema description fixes

The ${runtime.image.my-image.tag} → ${runtime.images.my-image.tag} typo (missing s) is consistently
fixed across all three files that mirror it: pkg/devspace/config/versions/latest/schema.go,
devspace-schema.json, and docs/schemas/config-openapi.json. ✓


PASS — patches.mdx import

FragmentInfoPrintConfig is imported and used at line 219. The partial (_partials/tip-print-config.mdx)
exists. ✓


One nitpick — test case name

The test case "top level" at depth=1 actually produces ## (h2), not h1. This is technically correct
since GenerateReference calls createSections with depth=1, but the name is slightly misleading. Not a
bug, but a reader could be confused.


Summary: One real fix needed — run cd docs && yarn install to remove the stale mermaid lockfile entries
before merging.

Fix generators, for example only 6 #'s are allowed now.

Signed-off-by: Ryan Swanson <ryan.swanson@loft.sh>
@zerbitx zerbitx marked this pull request as ready for review April 24, 2026 05:25
@zerbitx zerbitx merged commit c79950b into main Apr 24, 2026
17 of 20 checks passed
@zerbitx zerbitx deleted the fix-docs branch April 24, 2026 05:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant